## Summary
Reshape the speculation tree data model around the Base/Head path that
the build stage actually consumes, and align its store with the
speculation design.

entity: SpeculationPath{Base, Head} becomes the unit;
SpeculationPathInfo carries the path plus its Score, controller-owned
Status
(candidate/selected/prioritized/building/passed/failed/cancelling/cancelled),
and BuildID — Path is immutable once persisted, Score/Status/BuildID are
updateable by the controller. Score is scorer-computed and
controller-persisted dynamic state — recomputed on every respeculate,
not set at enumeration. Selected/Prioritized and Cancelling/Cancelled
split desire vs budget-cleared and cancel-intent vs terminal, so the
persisted status carries the cross-stage contract. Adds
SpeculationPathAction (Promote/Cancel) and SpeculationPathDecision for
the selector and prioritizer seams. SpeculationTree.Speculations becomes
Paths, and the tree gains a Version for optimistic locking (starts at 1,
incremented per change). The Build entity uses the shared
SpeculationPath (Head = the batch under verification) and drops its own
Score, which was never populated or read.

storage: SpeculationTreeStore.UpdateSpeculations(batchID,
[]SpeculationInfo) becomes a pure conditional write — Update(ctx,
batchID, oldVersion, newVersion, paths) — returning ErrVersionMismatch
when the persisted version does not match, per the repo's
optimistic-locking pattern (version arithmetic owned by the controller).
The MySQL impl treats rowsAffected == 1 as success, 0 as version
mismatch, and anything else as a generic error. The MySQL column
speculations is renamed paths and the schema gains a version column.
MySQL impl, mock, and storage integration coverage (create/get
round-trip, duplicate, versioned whole-tree overwrite, stale-write
rejection, not-found) added/updated.

## Test Plan


## Issues


## Stack
1. @ #231
1. #315
1. #316
1. #317
1. #320

## Summary
### Why?

The speculation seams being introduced up-stack (path scorer, selector,
prioritizer) and durable links from other entities (a path→build
mapping) all need to refer to one specific path inside a batch's
speculation tree. Restating the full Base/Head split in every seam
output couples those contracts to path structure and forces consumers to
compare ordered slices; a single opaque identity lets each seam return
only what matters — a path ID plus its verdict — and gives durable links
a stable key to hang on.

### What?

`entity.SpeculationPathInfo` gains `ID`: assigned by the controller when
the path entry is first persisted, immutable thereafter, and unique
within its tree. Its format is the controller's choice and carries no
meaning — it is never parsed. Everything outside the tree names a path
by this ID. The tree store persists it transparently through the JSON
`paths` column, so the change is additive with no schema migration.

## Test Plan
✅ `bazel test //submitqueue/entity/...` — entity suite passes; the field
rides the existing JSON round-trip in the tree store.

## Issues


## Stack
1. @ #337
1. #315
1. #316
1. #317
1. #320
1. #331
1. #332
1. #333

## Summary
Add the first speculation seam and its limit counterpart from the
speculation RFC, as vendor-agnostic extension interfaces under
submitqueue/extension/speculation/.

enumerator: given a batch and its active dependencies ordered
oldest-first (queue arrival order — the ordering that fixes which
assumed-good Base prefixes exist), mechanically lists the candidate
Base/Head speculation paths — pure, deterministic, and purely
structural. It returns only []entity.SpeculationPath: identity, status,
and score are controller-owned, and the controller wraps each path into
the persisted tree entry (SpeculationPathInfo), keeping a clean
ownership boundary between the seam and tree state.

dependencylimit: the "how much" policy bounding how many active
(in-flight) dependencies a batch may speculate over. It is the
eligibility gate before enumeration; unlike the other speculation limits
it is controller-held rather than injected into a seam, keeping the
enumerator pure. The value is signal-driven, not a fixed constant.

Each follows the repo extension contract (conflict.Analyzer reference
shape): Factory.For(Config) (T, error) with Config carrying only
QueueName; behavioral knobs and limit signals are integrator-injected at
construction. Includes READMEs, gomock packages, and Makefile mock-gen
wiring. Interfaces only; concrete impls and controller wiring are
deferred.

## Test Plan


## Issues


## Stack
1. #337
1. @ #315
1. #316
1. #317
1. #320
1. #331
1. #332
1. #333

Add the scorer seam from the speculation RFC, as a vendor-agnostic
extension interface under submitqueue/extension/speculation/pathscorer/.

The scorer computes each speculation path's predicted-success score from
the current state: the per-batch scores of the path's base batches
(entity.Batch.Score) and which of those dependencies have resolved
(landed or build-passed), plus optionally other signals. It is a
prediction over live state, so the controller re-runs it on every
respeculate right after reconciling status, and persists the result; the
scorer owns only the formula.

The controller hands it the batch's speculation tree directly — the
subject it scores. Any richer signal an implementation needs (dependency
batch scores, historical pass rates) is injected at its Factory, not put
in the signature. It never writes: its only output is per-path scores
([]entity.PathScore — path ID plus fresh score, an entity-level
seam-output type alongside the path-decision type), which the controller
merges into the tree and persists, staying the single writer of tree
state; structure and status never pass through the scorer. Scores are
probabilities in [0, 1] — the contract every implementation must
satisfy, enforced by the controller on consume.

This is the per-path scorer, distinct from the existing per-batch score
stage (`extension/scorer`) that sets entity.Batch.Score — the path
scorer consumes those to score whole paths.

Follows the repo extension contract: Factory.For(Config) (Scorer, error)
with Config carrying only QueueName. Includes README, gomock package,
and a programmable fake. The speculation RFC's seam descriptions are
updated to match the identity-keyed minimal-output contracts (and gain a
design-decision entry for assigned path identity). Interface only;
concrete impls and controller wiring are deferred.


## Stack
1. #337
1. #315
1. @ #316
1. #317
1. #320
1. #331
1. #332
1. #333

…320)

Add the queue-wide prioritizer seam and its limit counterpart from the
speculation RFC, as vendor-agnostic extension interfaces under
submitqueue/extension/speculation/.

prioritizer: selection is per batch and blind to other batches, so it
cannot ration a shared build budget. The prioritizer sees every path
across the queue's in-flight batches that runs or wants to run (Selected
/ Prioritized / Building, each carrying its ID and score), ranks them —
scores are probabilities in [0, 1] per the path scorer's contract — and
returns sparse decisions naming paths by ID: Promote to admit under the
budget, Cancel to preempt, at most one decision per path. Whether it
preempts at all is implementation policy (sticky-slots vs preemptive).
It never writes: the controller maps each decision back to its tree and
applies the status transition under that tree's optimistic lock.
Prioritized thus means exactly "admitted under the queue's build budget,
cleared to build, not yet building".

prioritizationlimit: the "how much" policy bounding the queue's
concurrent speculation builds — the budget the prioritizer admits
against. Injected into the prioritizer at construction and applied by
it, keeping the interface limit-free; the value is signal-driven, not a
fixed constant.

Each follows the repo extension contract: Factory.For(Config) (T, error)
with Config carrying only QueueName. Includes READMEs, gomock packages,
and programmable fakes. Interfaces only; concrete impls and controller
wiring are deferred.


## Stack
1. #337
1. #315
1. #316
1. #317
1. @ #320
1. #331
1. #332
1. #333